Error handling

Response envelope

All responses are wrapped in a success envelope at the top level, and list endpoints also wrap each item:

// Success (top-level)
{ "success": true, "data": { /* ... */ } }

// Failure (top-level)
{ "success": false, "failureCode": "INVALID_PARAMETERS", "message": "Bad input", "errorData": { /* optional */ } }

// Success list with per-item results
{
  "success": true,
  "data": [
    { "success": true, "data": { /* item */ } },
    { "success": false, "failureCode": "CLIP_NOT_FOUND", "message": "Clip 456 not found" }
  ]
}

• success: false responses always include a failureCode and may include errorData and message.
• message is intended for developers, not end users.

Failure codes

The failureCode values and their meanings:

FailureCode	Meaning
AUTHENTICATION_FAILED	The Bearer token could not be verified. Common causes are that the token is missing or has expired.
VALIDATION_ERROR	There was a problem with the request body. It should be fixed before trying again.
SERVICE_UNAVAILABLE	A dependent service or component is temporarily unavailable. Retry later.
INTERNAL_ERROR	Unexpected server error.
ACR_CLOUD_ERROR	Third‑party fingerprinting service returned an error.
ACR_CLOUD_CONFIG_ERROR	Fingerprinting service misconfiguration detected.
NO_STREAMING_RIGHTS	Content recognized but not licensed for requested region/usage.
CLIP_NOT_FOUND	Requested clip does not exist or is unavailable.
TRACK_NOT_FOUND	Requested track does not exist or is unavailable.
COLLECTION_NOT_FOUND	Requested collection does not exist or is unavailable.
INVALID_PARAMETERS	Missing/invalid parameters (e.g., mutually exclusive inputs not respected).
MISSING_HEADERS	Required headers (e.g., Authorization) missing or malformed.
NETWORK_ERROR	Transient network error contacting an upstream dependency.